---
title: "Avatar"
description: "The Avatar component is used to represent a user, and displays the profile picture, initials or fallback icon."
---

import {avatarContent} from "@/content/components/avatar";


# Avatar

The Avatar component is used to represent a user, and displays the profile picture, initials or fallback icon.

<ComponentLinks component="avatar" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add avatar",
    npm: "npm install @heroui/avatar",
    yarn: "yarn add @heroui/avatar",
    pnpm: "pnpm add @heroui/avatar",
    bun: "bun add @heroui/avatar"
  }}
/>


## Import

HeroUI exports 3 avatar-related components:

- **Avatar**: The main component to display an avatar.
- **AvatarGroup**: A wrapper component to display a group of avatars.
- **AvatarIcon**: The default icon used as fallback when the image fails to load.

<ImportTabs
  commands={{
    main: 'import {Avatar, AvatarGroup, AvatarIcon} from "@heroui/react";',
    individual: 'import {Avatar, AvatarGroup, AvatarIcon} from "@heroui/avatar";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={avatarContent.usage} />

### Sizes

<CodeDemo title="Sizes" files={avatarContent.sizes} />

### Disabled

<CodeDemo title="Disabled" files={avatarContent.disabled} />

### Bordered

<CodeDemo title="Bordered" files={avatarContent.bordered} />

### Radius

<CodeDemo title="Radius" files={avatarContent.radius} />

### Colors

<CodeDemo title="Colors" files={avatarContent.colors} />

### Avatar Fallbacks

If there is an error loading the `src` of the avatar, there are 2 fallbacks:

- If there's a `name` prop, we use it to generate the initials and a random, accessible background color.
- If there's no `name` prop, we use a default avatar.

If the `showFallback` is not passed, the fallbacks will not be displayed.

<CodeDemo title="Avatar Fallbacks" files={avatarContent.fallbacks} />

### Custom Fallback

You can also provide a custom fallback component to be displayed when the `src` fails to load.

<CodeDemo title="Custom Fallback" files={avatarContent.customFallback} />

### Custom Implementation

In case you need to customize the avatar even further, you can use the `useAvatar` hook to create your own implementation.

<CodeDemo showPreview={false} showOpenInCodeSandbox={false} title="Custom implementation" files={avatarContent.customImpl} />
  

### Custom initials logic

It is possible to customize the logic used to generate the initials by passing a function to the `getInitials` prop.
By default we merge the first characters of each word in the `name` prop.

## Avatar Group

<CodeDemo title="Avatar Group" files={avatarContent.group} />

### Group Disabled

<CodeDemo title="Group Disabled" files={avatarContent.groupDisabled} />

### Group Max Count

You can limit the number of avatars displayed by passing the `max` prop to the `AvatarGroup` component.

<CodeDemo title="Group Max Count" files={avatarContent.groupMax} />

### Group Total Count

You can display the total number of avatars by passing the `total` prop to the `AvatarGroup` component.

<CodeDemo title="Group Total Count" files={avatarContent.groupTotal} />

### Group Custom count

`AvatarGroup` provides a `renderCount` prop to customize the count displayed when the `total` prop is passed.

<CodeDemo title="Group Custom count" files={avatarContent.groupCustomCount} />

### Group Grid

By passing the `isGrid` prop to the `AvatarGroup` component, the avatars will be displayed in a grid layout.

<CodeDemo title="Usage" files={avatarContent.groupGrid} />

### Group Custom Implementation

In case you need to customize the avatar group even further, you can use the `useAvatarGroup` hook and the
`AvatarGroupProvider` to create your own implementation.

<CodeDemo showPreview={false} showOpenInCodeSandbox={false} title="Custom implementation" files={avatarContent.groupCustomImpl} />

## Slots

- **base**: Avatar wrapper, it includes styles for focus ring, position, and general appearance.
- **img**: Image element within the avatar, it includes styles for opacity transition and size.
- **fallback**: Fallback content when the image fails to load or is not provided, it includes styles for centering the content.
- **name**: Initials displayed when the image is not provided or fails to load, it includes styles for font, text alignment, and inheritance.
- **icon**: Icon element within the avatar, it includes styles for centering the content, text inheritance, and size.

### Custom Avatar Styles

You can customize any part of the avatar by using the `classNames` prop, each `slot` has its own `className`.

<CodeDemo title="Custom Avatar" files={avatarContent.custom} />

<Spacer y={4} />

## Data Attributes

`Avatar` has the following attributes on the `base` element:

- **data-hover**:
  When the avatar is being hovered. Based on [useHover](https://react-spectrum.adobe.com/react-aria/useHover.html)
- **data-focus**:
  When the avatar is being focused. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html), it is applied when `isFocusable` is `true` or when the `as` property is assigned as `button`.
- **data-focus-visible**:
  When the avatar is being focused with the keyboard. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html), it is applied when `isFocusable` is `true` or when the `as` property is assigned as `button`.

<Spacer y={4} />

## API

### Avatar Props

<APITable
  data={[
    {
      attribute: "src",
      type: "string", 
      description: "The source URL of the image to be displayed.",
      default: "-"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "Sets the avatar background color.",
      default: "default"
    },
    {
      attribute: "radius",
      type: "none | sm | md | lg | full",
      description: "Sets the avatar border radius.",
      default: "full"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "Sets the avatar size.",
      default: "md"
    },
    {
      attribute: "name",
      type: "string",
      description: "Displays the initials if the image is not provided or fails to load.",
      default: "-"
    },
    {
      attribute: "icon",
      type: "ReactNode",
      description: "Displays a custom icon inside the avatar.",
      default: "-"
    },
    {
      attribute: "fallback",
      type: "ReactNode",
      description: "A custom fallback component to display when the image fails to load.",
      default: "-"
    },
    {
      attribute: "isBordered",
      type: "boolean",
      description: "If true, adds a border around the avatar.",
      default: "false"
    },
    {
      attribute: "isDisabled",
      type: "boolean", 
      description: "If true, disables the avatar and applies a disabled styling.",
      default: "false"
    },
    {
      attribute: "isFocusable",
      type: "boolean",
      description: "If true, makes the avatar focusable for keyboard navigation.",
      default: "false"
    },
    {
      attribute: "showFallback",
      type: "boolean",
      description: "If true, shows the fallback icon or initials when the image fails to load.",
      default: "false"
    },
    {
      attribute: "ImgComponent",
      type: "React.ElementType",
      description: "The component to be used as the image element.",
      default: "img"
    },
    {
      attribute: "imgProps",
      type: "ImgComponentProps",
      description: "Props to be passed to the image element.",
      default: "-"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\" | \"img\" | \"fallback\" | \"name\" | \"icon\", string>>",
      description: "Allows to set custom class names for the avatar slots.",
      default: "-"
    }
  ]}
/>

### Avatar Group Props

<APITable
  data={[
    {
      attribute: "max",
      type: "number",
      description: "The maximum number of visible avatars",
      default: "5"
    },
    {
      attribute: "total",
      type: "number", 
      description: "Control the number of avatar not visible",
      default: "-"
    },
    {
      attribute: "size",
      type: "AvatarProps['size']",
      description: "Size of the avatars",
      default: "-"
    },
    {
      attribute: "color",
      type: "AvatarProps['color']",
      description: "Color of the avatars",
      default: "-"
    },
    {
      attribute: "radius",
      type: "AvatarProps['radius']",
      description: "Radius of the avatars",
      default: "-"
    },
    {
      attribute: "isGrid",
      type: "boolean",
      description: "Whether the avatars should be displayed in a grid",
      default: "false"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the avatars are disabled",
      default: "-"
    },
    {
      attribute: "isBordered",
      type: "boolean",
      description: "Whether the avatars have a border",
      default: "-"
    },
    {
      attribute: "renderCount",
      type: "(count: number) => ReactNode",
      description: "This allows you to render a custom count component.",
      default: "-"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\" | \"count\", string>>",
      description: "Allows to set custom class names for the avatar group slots.",
      default: "-"
    }
  ]}
/>
